<h3>Plugin overview</h3>

<p>This plugin lets you manage a database of links from your admin area and maintains a count of how many times each link has been clicked on by reader. When used as a skin variable, it displays a redirector URL in the form of /nucleus/plugins/blogroll/?n=id, or a group of such URLs.</p>
<h3>SkinVars</h3>

Parameters: Type, ID, Sort field, Sort order, GroupDesc, NumOfLinks, Redirect

<dl>
	<dt><b>Type</b> - 'group' | 'link' | 'user'</dt>
	<dd>Tells plugin whether to display an individual link or a group of links as defined in the admin area, or a single user's links.</dd>
	<dt><b>ID</b></dt>
	<dd>If <b>Type</b> is 'group', this should be the name of the group(s) to display. Use the pipe character ('|') to separate multiple group names. If <b>Type</b> is 'link', this should be the numeric ID of the link to display. If <b>Type</b> is 'user', this should be the short name (login name) of the user whose blogroll should be displayed. If the user specified is not a member of the team for the blog being displayed, the blogroll will <i>not</i> be shown.</dd>
	<dt><b>Sort field</b> (optional) - '<u>order</u>' | 'url' | 'text' | 'desc' | 'created' | 'clicked' | 'counter' | 'random' </dt>
	<dd>If <b>Type</b> is 'group', tells plugin in what order to display links. Defaults to 'order', which displays links according to the order defined in admin area. If <b>Type</b> is 'link', place the <b>Redirect</b> value here.</dd>
	<dt><b>Sort order</b> (optional) - '<u>asc</u>' | 'desc'</dt>
	<dd>If <b>Type</b> is group, tells plugin whether to display links in ascending or descending order according to the field defined in <b>Sort field</b>. Defaults to 'asc'.</dd>
	<dt><strong>GroupDesc</strong> (optional)</dt>
	<dd>If <strong>ID</strong> defines multiple groups to display links from, the <strong>GroupDesc</strong> value will determine what will replace the <code>&lt;%groupdesc%&gt;</code> variable in the blogroll template. If no <strong>GroupDesc</strong> is specified, the description of the first group will be used.</dd>
	<dt><strong>NumOfLinks</strong> (optional)</dt>
	<dd>If <strong>Type</strong> is group, tells plugin to display only a specified number of links. Must be a positive integer value; if not, plugin will display all links. </dd>
  <dt><strong>Redirect</strong> (optional)</dt>
	<dd>Set to "yes" or "no" to override the default as set in Blogroll's plugin options to determine whether to show the redirector URL or the regular URL.</dd>
</dl>
<h3>Example Usage  </h3>
<ul>
<li><code>&lt;%Blogroll(group,blogs)%&gt;</code>: displays the group of links named 'blogs'</li>
<li><code>&lt;%Blogroll(group,mac,clicked,desc)%&gt;</code>: display the group of links named 'mac', from the most recently clicked to the least recently clicked</li>
<li><code>&lt;%Blogroll(group,blogs|news|mac,text,desc,Blogroll)%&gt;</code>: displays links from 'blogs', 'news' and 'mac, sorted by text in descending order, and using 'Blogroll' as a collective group description</li>
<li><code>&lt;%Blogroll(group,news|mac,random,,News,10)%&gt;</code>: displays 10 random links from 'news' and 'mac'.</li>
<li><code>&lt;%Blogroll(link,5,yes)%&gt;</code>: displays the link for link #5, displaying the redirector URL even if the plugin option is set to "no".</li>
<li><code>&lt;%Blogroll(user,johndoe)%&gt;</code>: displays all groups and links for the member with short name "johndoe".</li>
</ul>


<h3>Template Options</h3>

In the plugin options page, you can specify how links will appear on your page. The variables available for use in all fields <i>except</i> 'Item' are:
<ul>
<li><code>&lt;%groupid%&gt;</code>: the group's internal id number </li>
<li><code>&lt;%groupname%&gt;</code>: the group name</li>
<li><code>&lt;%groupdesc%&gt;</code>: the group's description</li>
</ul>
Variables available for use in the item template are:
<ul>
<li><code>&lt;%id%&gt;</code>: the link's id number</li>
<li><code>&lt;%linkurl%&gt;</code>: the link's redirector URL as generated by the plugin</li>
<li><code>&lt;%linktitle%&gt;</code>: the link's description</li>
<li><code>&lt;%linktext%&gt;</code>: the link text</li>
<li><code>&lt;%linkcounter%&gt;</code>: number of times the link has been clicked (not available if redirection is off)</li>
<li><code>&lt;%linkcomment%&gt;</code>: user comment of a link</li>
<li><code>&lt;%linkdesc%&gt;</code>: description of a link</li>
<li><code>&lt;%linkdesccomm%&gt;</code>: show link description, show comment instead if description not available</li>
<li><code>&lt;%sep%&gt;</code>: seperator (i.e. '-')</li>
<li><code>&lt;%linkedit%&gt;</code>: link to edit an item</li>
<li><code>&lt;%linkclicked%&gt;</code>: date and time the link was last clicked  (not available if redirection is off)</li>
<li><code>&lt;%linkcreated%&gt;</code>: when the link was created </li>
<li><code>&lt;%xfn%&gt;</code>: XHTML Friend Network information</li>
</ul>

If the <code>&lt;%Blogroll%&gt;</code> skinvar is used to call a single link, the item template will be used to display the link.<br/>
<br/>
Note: &lt;%linktext%&gt; has been removed.

<h3>Tagging Support</h3>
Since 0.35, tagging function is added. The blogroll function continues to function as before. On the other hand, there is a tag field when add/edit a link.

To integrate the tagging function with the blog, a tagcloud can be created:
<ol>
  <li>clone the skin you use on the blog</li>
  <li>rename it to 'blogroll'</li>
  <li>edit the main index in the blogroll skin, replace the &lt;%blog(...)%&gt; to &lt;%Blogroll(tagcloudresult%&gt;, and
  replace the sidebar line (i.e.  &lt;%parsedinclude(sidebar.inc)%&gt;) to &lt;%Blogroll(tagcloud,group)%&gt; (replace group with your blogroll group name)</li>
  <li>create a blogroll.php (see a sample in package) and place it in your blog's root directory</li>
  <li>link to the blogroll page from your blog's sidebar</li>
  <li>add css changes to decorate the tagcloud (see smaple in package)</li>
</ol>

There are 2 new skinvar added to be used in a tagcloud Blogroll page:
<ul>
  <li>&lt;%Blogroll(tagcloud,[group]%&gt; - to display a tagcloud for a particular group</li>
  <li>&lt;%Blogroll(tagcloudresult)%&gt; - display all links for a tag (select from the tagcloud)</li> 
</ul>

<h3>del.icoc.us Support</h3>
Since v0.36, user can send blogroll links to del.icoc.us. To enable this function:
<ol>
  <li>Enable del.icoc.us function from plugin option after installing the plugin</li>
  <li>User set their del.icoc.us user and password in member setting</li>
</ol>

<h3>Keyword search function</h3>
Since v0.40, a keyword search is also search in the blogroll page. New Skinvar &lt;%Blogroll(searchbox, [group])%&gt; can be used to add the search box.

<h3>Support and Bug reports</h3>

<p>For additional support and/or bug reports please use this forum thread:
<a href="http://forum.nucleuscms.org/viewtopic.php?t=9219">
http://forum.nucleuscms.org/viewtopic.php?t=9219</a></p>

<h3>XFN support</h3>
As of v0.42, XFN 1.1 support is added. To fully enable the XFN function, user should modify &lt;head&gt; to &lt;head profile="http://gmpg.org/xfn/11"&gt; in their skin. A new
field of XFN is added in add/edit link and bookmarklet

<h3>Version History</h3>

<ul>
<li>0.42    (2008) admun (Edmond Hui)
  <ul>
    <li>XFN 1.1 support</li>
  </ul>
</li>
<li>0.41    (Jan 14, 2008) admun (Edmond Hui)
  <ul>
    <li>add ticket check in plugin admin menu as required for v3.3</li>
    <li>edit link code re-factor</li>
    <li>pagination for link/tag management</li>
    <li>search box result should only return items from current group</li>
    <li>fix related tag with proper group</li>
    <li>fix edit link redirect URL</li>
    <li>add tag auto completion</li>
    <li>show tags on search result, with link to it</li>
  </ul>
</li>
<li>0.40    (Jul 2007) admun (Edmond Hui)
  <ul>
    <li>htmlspecialchars_decode PHP4 support</li>
    <li>add search function</li>
    <li>add related tag function in tagcloud</li>
  </ul>
</li>
<li>0.39    (May 9 2007) admun (Edmond Hui)
  <ul>
    <li>Fixed PluginAdmin inclusion in bookmarklet and links.php</li>
    <li>Fixed " in query Mysql update error</li>
    <li>Seperate CSS decoration with NP_TechnoratiTags</li>
    <li>Add redirection after edit link from blogroll page</li>
  </ul>
</li>
<li>0.38    (12 April 2007) admun (Edmond Hui)
  <ul>
    <li>Fixed incorrect delete link result handling from managetag</li>
    <li>Added lgroup id fot list header</li>
  </ul>
</li>
<li>0.37    (18 March 2007) admun (Edmond Hui)
  <ul>
    <li>Added tagcloud decoration</li>
    <li>Fixed admin tag menu functions</li>
    <li>Fixed utf-8 support</li> 
    <li>Added rename/delete tag (currently not fully working, delete tag rename it to "deleted".... still finding a way to do that</li>
    <li>Added replace "+" with " " plugin option</li>
    <li>Added show #links without tag at the end of managelinks</li>
    <li>Fixed no delete/rename tag after edit in managetag</li>
    <li>Fixed missing tag/comment when error in bookmarklet</li>
  </ul>
</li>
<li>0.36    (8 March 2007) admun (Edmond Hui)
  <ul>
    <li>Option for tagcloudresult header</li>
    <li>Fixed tagcloud result list only to group specified</li>
    <li>Fixed getTableList() bug</li>
    <li>Added template options for tagcloud link display</li>
    <li>Added tagcloud link click count</li>
    <li>del.icio.us support</li>
  </ul>
</li>
<li>0.35    (March 2007) admun (Edmond Hui)
  <ul>
    <li>Initial release with tagging function</li>
  </ul>
</li>
<li>0.30    (4 March 2006)
  <ul>
    <li>Added option to display a single user's blogroll.</li>
    <li>Admin area for managing links now shows current group.</li>
  </ul>
</li>
<li>0.27    (27 October 2005)
  <ul>
    <li>Added redirector option for skin variable.</li>
    <li>Fixed bug in groups.php that led to potential HTTP 405 error.</li>
    <li>Fixed bug in bookmarklet URL that screwed up non-English document titles.</li>
  </ul>
</li>
<li>0.25    (30 April 2005)
  <ul>
    <li>Changed output of skinvar to encode HTML entities for standards compliance.</li>
    <li>Changed skinvar behaviour to let groupdesc parameter override 
         db-set groupdesc for single-group skinvar calls.</li>
    <li>Fixed an issue where text/titles in edit forms (index.php) and add
               forms (bookmarklet.php) were showing backslash-escaped text.</li>
    <li>Fixed an issue where sorting by counter was not working. </li>
  </ul>
</li>
<li> 0.23 (27 April 2005)
  <ul>
    <li>Added a bookmarklet for adding links. </li>
    <li>Fixed an issue where after deleting a link, the group link list is displayed twice. </li>
    <li>Added option for 'sortfield' parameter to sort links randomly.</li>
    <li>Added parameter to display only a specified number of links.</li>
    <li>Corrected some references to Redirect.</li>
    <li>Fixed an issue where deleting a group did not also delete the links in that group.</li>
	  <li> Fixed an issue where plugin was making too many SQL queries to display a group of links.</li>
    <li> Added &lt;%groupid%&gt;, &lt;%linkcreated%&gt; and &lt;%linkclicked%&gt; to templates.</li>
  </ul>
</li>
<li>0.20 (22 April 2005)
		<ul>
			<li>Changed plugin name to NP_Blogroll since redirection is now merely an option.</li>
	  	<li> Fixed a bug that caused template for list footer and footer to not be parsed properly.</li>
	  	<li> Added option to turn off redirection feature.</li>
	  	<li> Added option to call multiple groups of links with a single skinvar call.</li>
	  	<li>Removed &lt;%groupid%&gt; from templates. </li>
		</ul>
</li>
<li>0.18 (20 April 2005)
		<ul>
			<li>Added sorting options (sort by order, name, url and asc/desc). </li>
	  	<li>Fixed a minor bug that was causing the plugin to not update the counter.</li>
	  	<li>Removed skinvar parameter to display only counter (use template to display counter).</li>
		</ul>
</li>
<li>0.17 (14 April 2005)
  	<ul>
  		<li>Added ability to move a link from one group to another</li>
  		<li>Fixed bugs preventing changing group order from functioning as intended</li>
 		</ul>
</li>
<li>0.16 (14 April 2005)
  <ul>
  <li>Added ability for grouping links together and to call a group of links from a skinvar</li>
  <li>Plugin now uses a template to display a link or group of links</li>
  <li>Plugin now keeps separate links for each user.</li>
  </ul>
</li>
<li>0.15 (5 April 2005)
  <ul>
  <li>Plugin will now check client's user agent against a list of known bots and will not increment the counter if client is a bot.</li>
  </ul>
</li>
<li>0.14 (1 April 2005)
  <ul>
  <li>Added a second parameter for the skinvar to display link counter instead.</li>
  </ul>
</li>
<li>0.13 (1 April 2005)
  <ul>
  <li>Fixed a minor bug in redirect/index.php that was causing the plugin to not update the counter.</li>
  </ul>
</li>
<li>0.12 (1 April 2005)
  <ul>
  <li>Admin page now truncates long URLs for display purposes</li>
  <li>Generated link will now use the link text as title attribute if title is not specified</li>
  </ul>
</li>
<li>0.11 (1 April 2005)
  <ul>
  <li>Fixed a minor bug.</li>
  </ul>
</li>
<li>0.10 (1 April 2005)
  <ul>
  <li>Initial release.</li>
  </ul>
</li>
</ul>

<h3>License Information</h3>
<p><a href="http://creativecommons.org/licenses/GPL/2.0/">Copyright &copy; 2005</a> <a href="http://www.ketsugi.com">Joel Pan</a> </p>
